Assurance API
Support and FAQs
To get support from our team and view the status of the APIs, view our Support page.
Get Products
Why is a different response payload received for different product types?
The Get Product API call queries our inventory, address database, orders and problem reports. The API will return as much rich information as we have available in order to support problem resolution. The information we have available will vary by product instance.
Diagnostics
When creating a new diagnostic, what happens if a diagnostic session already exists for the same product instance?
If it has been is less than one hour since the last interaction, that last interaction is reused, otherwise a new session is created.
Under what circumstances should a diagnostic be cancelled?
A diagnostic session should only be cancelled if an incorrect product type has been submitted in the request.
What are the expected response times for a diagnostic?
Response times will vary depending on the product type and the type of test run. Because of the asynchronous nature of the diagnostic API, there are two times to consider:
- The Diagnostic API which should respond within half a second.
The time for the actual test to complete running, depending on the type of test. Average times are:
- ONT Status, 10 seconds or less
- Single Line Test, 32 seconds or less
- Line State Diagnosis Test, 15 seconds or less
- Electrical Test, 50 seconds or less.
How will I know when the diagnostic is complete?
You will need to poll the Assurance API until status ‘Complete’ is returned. We suggest you set polling to a 10 second interval.
Problem Reports
Can a problem report be submitted a without having first run a diagnostic?
No, this is a process-driven API. The diagnosis flow on the service must be completed prior to logging a fault to ensure the correct information is submitted and the problem can be resolved as quickly as possible.
What happens when a problem report is submitted?
A problem ticket is submitted to our ITSM problem management system and is automatically allocated to the appropriate resolver group. A reference number is returned as part of the API response. When the problem report is submitted, the diagnostics session is completed.
How can an appointment time be changed?
To request a change of appointment time, either submit an update to the problem report with some appointment options for Assure to select from, or depending on the status of the problem report, cancel and resubmit the problem report.
Can a problem report be submitted without an appointment booking?
In most cases an appointment booking with a commitmentType of BETWEEN is required for problem report submission.
Situations where appointment bookings are not required are:
- Unvalidated Products
- No scheduled timeslots have been loaded for the next 21 calendar days
- Scheduling system is unavailable
How do I know if I can submit a problem report without an appointment booking?
The requirement for a given session to have an appointment booking for a problem report is indicated in two ways
Product Configuration
The product configuration (found under product.configuration.problemReport.product) indicates the appointment booking behaviours allowed.
The three fields which denote this are:
- allowBetweenBookings
- allowsByBookings
- allowsASAPBookings
If only allowBetweenBookings is true - then an appointment booking is required for a given session.
If any other fields are true - then an appointment booking is not required for a given session.
Query Schedule Endpoint response
If the scheduling subsystem is unavailable the reservationPossibleForProduct field on the query response will be set to false, this indicates reservations for the given product are not possible, and a problem report can be submitted without a reservation.
How do you determine that no timeslots are available for the next 21 calendar days?
This is determined once an API consumer has queried dates which cover the next 21 calendar days - through either one or multiple requests to Query Schedule (GET sessions/{sessionid}/schedule). Has queried?
This is done based on API consumer requests because appointment availability changes in real time based on consumption via all API consumers.
How should the reserve appointment start and end datetimes be determined?
The Query Schedule (GET sessions/{sessionid}/schedule) should be used to retrieve the available appointment start and end datetimes, and these should be used to select and then submit suitable times for a reservation added the word and
Can I fail to reserve an appointment because the timeslot has been taken?
An appointment reservation can fail because another API consumer (or another user from the same API consumer) consumes the timeslot with their appointment booking.
If this occurs the reservationStatus will be NO_AVAILABLE_TIMESLOTS_FOR_REQUESTED_PERIOD in the appointment reservation response.
If this situations occurs you will need to select a new timeslot and submit a new reservation request.
What datetime format and timezone is used for schedule and reservation datetime fields?
The Query Schedule (GET sessions/{sessionid}/schedule) and (POST sessions/{sessionid}/reservations) express time in local date time format in the New Zealand timezone.
How long are appointment bookings guaranteed for?
When the reserve appointment request returns a successful response (HTTP 200), (reservationStatus: "REQUESTED_TIMESLOT"), the appointment is booked and guaranteed while a given diagnostic session is active/valid.
What is the difference between amending and updating a problem report?
Amending a problem report enables all edible properties of the original problem to be resubmitted. Updating a problem report adds additional information to the report, for example “Tech replaced faulty card”.
Can a closed problem report be amended?
No. Once a problem report is closed, a new diagnosis and problem report must be submitted.
Can a second problem report be opened for the same product instance if there is already one open?
No, this is not supported as part of our BAU Assure process.
Events
Can I still log a problem report if my service is effected by an event but not event related?
Yes, This is known as a secondary fault and will be processed as usual.